Usenet 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / x / volume6 / xpwdoc / part01 next >

Wrap

Internet Message Format | 1990-04-11 | 77.9 KB

Path: uunet!tut.cis.ohio-state.edu!zaphod.mps.ohio-state.edu!uakari.primate.wisc.edu!ames!sun-barr!newstop!sun!NSFnet-Relay.AC.UK From: jonm%syma.sussex.ac.uk@NSFnet-Relay.AC.UK (Jonathan Meyer) Newsgroups: comp.sources.x Subject: v06i065: Xpw Documentation, Part01/02 Message-ID: <134353@sun.Eng.Sun.COM> Date: 12 Apr 90 07:36:14 GMT Sender: news@sun.Eng.Sun.COM Lines: 1853 Approved: argv@sun.com Submitted-by: Jonathan Meyer <jonm%syma.sussex.ac.uk@NSFnet-Relay.AC.UK> Posting-number: Volume 6, Issue 65 Archive-name: xpwdoc/part01 #! /bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh <file", e.g.. If this archive is complete, you # will see the following message at the end: # "End of archive 1 (of 2)." # Contents: doc doc/help/PopComposite doc/help/PopCore # doc/help/PopGraphic doc/help/PopPixmap doc/help/PopScrollText # doc/help/PopWidgets doc/help/PopWidgets.news doc/ref/PopComposite # doc/ref/PopCore doc/ref/PopGraphic doc/ref/PopPixmap # Wrapped by jonm@csunb on Wed Apr 4 16:16:14 1990 PATH=/bin:/usr/bin:/usr/ucb ; export PATH if test ! -d 'doc' ; then echo shar: Creating directory \"'doc'\" mkdir 'doc' fi if test -f 'doc/help/PopComposite' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/help/PopComposite'\" else echo shar: Extracting \"'doc/help/PopComposite'\" $1809 characters$ sed "s/^X//" >'doc/help/PopComposite' <<'END_OF_FILE' XHELP *PopComposite Jonathan Meyer, Jan 1990 X XPoplog Widget Set, revision 3. X XThis file describes the Pop-11 interface to the PopComposite widget Xclass. For details of the PopComposite widget, see REF *PopComposite. XFor information on other widgets in the Poplog Widget Set, see HELP X*PopWidgets. X X XContents X X-- Introduction ------------------------------------------------------- X X XComposite widgets are used to as containers for other widgets. Each Xcomposite widget has a list of children (called the managed set), Xand has procedures for adding or removing widgets from this set X(managing or unmanaging widgets). Composite widgets with different Xpolicies for determining the geomoetry of their children are used Xto make list widgets, vpaned widgets, etc. A key part of the XComposite widget is its Resize procedure, which is used to Xrecalculate the geometry of the children widgets when the composite Xwidget is resized. Composite widgets can contain further composite Xwidgets, allowing for different layout schemes within the same Xwindow. X XThis file descibes how to load and use the PopComposite widget class, Xwhich is a direct descendant of the Composite widget class that is Xprovided in the Xt intrinsics. The PopComposite widget adds a callback Xlist to the structure of the Composite widget. The callback is used to Xnotify clients of resize events, and when the managed set of children of Xthe composite widget is changed. X XOther documentation is available to describe Composite widgets in detail X(see below). X X-- Loading the PopComposite Widget ------------------------------------ X XTo load the PopComposite widget class, either use X X LIB *PopComposite - loads only the PopComposite widget Xor X LIB *PopWidgets - loads all of the Poplog Widgets. X X X X XRelated Documentation X XXtIntrinsics Programmers Guide END_OF_FILE if test 1809 -ne `wc -c <'doc/help/PopComposite'`; then echo shar: \"'doc/help/PopComposite'\" unpacked with wrong size! fi # end of 'doc/help/PopComposite' fi if test -f 'doc/help/PopCore' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/help/PopCore'\" else echo shar: Extracting \"'doc/help/PopCore'\" $6481 characters$ sed "s/^X//" >'doc/help/PopCore' <<'END_OF_FILE' XHELP *PopCore Jonathan Meyer, Jan 1990 X XPoplog Widget Set, revision 3. X XThis file describes the Pop-11 interface to the PopCore Xwidget class, which is part of the XPoplog Widget Set. For details of other widgets in the Poplog Widget XSet, see HELP *PopWidgets. For more details of the PopCore Xwidget class, see REF *PopCore. X X X CONTENTS - (Use <ENTER> g to access required sections) X X -- PopCore Widget X -- PopCore Resources X -- Resource Notes X -- Further Notes X -- Actions X -- Translations X -- Methods X X-- PopCore Widget ----------------------------------------------------- X XThe PopCore widget is similar to the Core widget class but with more Xresources, and a callback list that is activated through an action. You Xcan specify the events that the callback is activated on using the Xtranslation table. The PopCore widget has a Graphics Context, which is Xused to hold resources like line width, line style, foreground and Xbackground colours etc. This graphics context is used by subclasses of the XPopCore widget class in graphics and text operations. X XThe PopCore widget class is intended as a base for building more Xsophisticated widget classes. As such, it is probably of limited use to Xapplications, which will probably use subclasses of PopCore, such as the XPopGraphic widget class. X X-- PopCore resources -------------------------------------------------- X Xxt_value(<widget>,XtNautoFlush) -> <boolean> X<boolean> -> xt_value(<widget>,XtNautoFlush) X Auto flushing occurs after you have performed some action (method) X on widgets which are subclasses of PopCore. An auto flush works X simply by calling XFlush with the relevant arguments. By disabling X auto flushing, you can perform multiple operations without having to X wait for the X Server to respond. When you have finished the X operations, reset auto flusing to on, and the operations will be X processed in one batch. This can be much more efficient than waiting X for each action to be processed. For example: X X false -> xt_value(w, XtNautoFlush); X repeat 100 times X XpwDrawPoint(w, random(100),random(100)); X /* draw 100 points and then flush the buffer */ X endrepeat; X true -> xt_value(w, XtNautoFlush); X Xxt_value(<widget>,XtNpointerShape) -> shape Xshape -> xt_value(<widget>,XtNpointerShape) X Changing the pointerShape resource affects the cursor that is used X when the mouse pointer is within the widgets window. See X XpwSetCursor below for an easier method of setting standard cursors. X X X-- Methods --------------------------------------------------------------- X XFor more information about Poplog Widget Methods, see REF X*XpwCallMethod and REF *XpwMethods. X XPopCore widgets respond to six methods: XpwSetColor, XpwFreeColor, XXpwSetFont, XpwFreeFont, XpwSetCursor and XpwFreeCursor. These methods Xemploy caches so that the application can repeatedly change colors, fonts Xand cursors without expensive calls to the X Server. X XXpwSetColor(<widget>, <name:string>); X This method is used to set the foreground of a widget to the named color. X It works as follows: if the color cache has not yet been initialized, X a new cache is created, with two entries - XtDefaultForeground and X XtDefaultBackground. The first entry is used if the name string is NULL. X If the name string isn't null, it is converted into a lowercase quark, and X the cache is searched for an entry whose key is that quark. If an entry X does not exist, and a call to XParseColor/XAllocColor is successful, the X returned color is added to the cache. If both attempts to locate the color X fail, the method returns with a result of zero. Otherwise, the method uses X XtSetValues to set the foreground of the widget, and returns with the X new color's pixel value. X XXpwFreeColor(<widget>, <name:string>); X FreeColor will search the color cache for the named color. If X an entry in the cache exists, the related XColor is released using X XFreeColor, and the cache entry is removed. You cannot free the XtDefault X cache entries -they are always available to XpwSetColor calls. If you free X a color which is the current foreground of the widget, the method calls X XpwSetColor to set the foreground of the widget to the default foreground. X XXpwSetFont(<widget>, <fontname:string>); X This method works as follows: if the font cache has not yet been X initialized, a new cache is created, with one entry - XtDefaultFont. X This entry is used if the fontname string is NULL. If the fontname string X isn't null, it is converted into a lowercase quark, and the cache is X searched for an entry whose key is that quark. If an entry does not exist, X and a call to XLoadQueryFont is successful, the returned font is added to X the cache. If both attempts to locate the font fail, the method returns X with a result of zero. Otherwise, the method uses XtSetValues to set the X font of the widget, and the method returns with the font's ID. X XXpwFreeFont(<widget>, <fontname:string>); X FreeFont will search the font cache for a font whose name is fontname. X If an entry in the cache exists, the related XFontStruct is released using X XFreeFont, and the cache entry is removed. You cannot free the XtDefaultFont X cache entry - this font is always available to XpwSetFont calls. If you X free a font which is the current font for the widget, the method calls X XpwSetFont to set the font of the widget to the default font. X XXpwSetCursor(<widget>, <shape:integer>); X XpwSetCursor first checks to see if the cursor cache exists. If it does X not exist, a new cache is created, with no entries. Otherwise the cache X is searched for the requested cursor shape (XC_crosshair, XC_arrow etc). X If an entry in the cache does not exist, the method calls XCreateFontCursor X to load the requested cursor shape, which is then added to the cache. X Then the method uses XtSetValues to set the pointerShape resource of the X widget. The cursor returned from XCreateFontCursor is returned. X XXpwFreeCursor(<widget>, <shape:integer>); X This method first checks the cursor cache for an entry corrosponding to X shape. If that entry exists, PopFreeCursor uses XFreeCursor to release the X memory associated with the cursor. If the current cursor for the widget is X the same as shape, XtSetValues is used to set the cursor to the server X default (ie. using XUndefineCursor). END_OF_FILE if test 6481 -ne `wc -c <'doc/help/PopCore'`; then echo shar: \"'doc/help/PopCore'\" unpacked with wrong size! fi # end of 'doc/help/PopCore' fi if test -f 'doc/help/PopGraphic' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/help/PopGraphic'\" else echo shar: Extracting \"'doc/help/PopGraphic'\" $6681 characters$ sed "s/^X//" >'doc/help/PopGraphic' <<'END_OF_FILE' XHELP PopGraphic Jonathan Meyer, Mar 1990 X XPoplog Widget Set, revision 3. X XThis file describes the Pop-11 interface to the PopGraphic widget class. XFor details of the PopGraphic widget class, see REF *PopGraphic. HELP X*PopWidgets outlines the Poplog Widget Set. See HELP *xt_graphic for Xdetails of a higher level interface is provided for users using LIB X*xt_graphic. PWM compatibility routines using this widget class are Xdescribed in HELP *xt_pwm X X X CONTENTS - (Use <ENTER> g to access required sections) X X -- Introduction X -- Functions for drawing on the widget X -- Text functions X -- Image dumping functions X -- Window functions X -- Colormap operations X -- Functions that return (integer) values about the display X -- Functions that alter the Graphics Context X -- Draw Functions X -- Related Documentation X X-- Introduction ------------------------------------------------------- X XLib PopGraphic loads the "Popgraphic" widget class (from the Poplog XWidget Set) and assigns the widget_class record created to the Xvariable -PopGraphic-. (See SHOWLIB *xt_load_wc, HELP *xt_core, HELP X*xt_widgets). This widget class creates widgets which are simple Xgraphics planes, on which you can draw lines, dump images, write text Xetc.. Lib PopGraphic also provides a number of routines for doing these Xthings, described below. X XA higher level interface to the PopGraphic widget is provided by Xroutines in LIB xt_graphics (see HELP *xt_graphic) X X X-- Functions for drawing on the widget -------------------------------- X XXpwDrawPoint(<widget>, x, y) X Draws a single point (x,y). X XXpwDrawPoints(<widget>, pts) X Draws a single point (x,y). X XXpwDrawLine(<widget>, x1, y1, x2, y2) X Draws a line between the points (x1,y1) and (x2, y2). X XXpwDrawRectangle(<widget>, x, y, width, height). X Draws a rectangle top left corner x,y. X XXpwDrawArc(<widget>, x,y, width, height, start_angle, extent) X Draws an arc, whose top left coord is x,y and of width*height X size. The start_angle is measured from the three O'clock position, X and the arc continues for extent degrees. start_angle and extent X are measured in 64ths of a degree. X X X-- Text functions ----------------------------------------------------- X XXpwWriteString(<widget>, x,y, <string>) X Writes the string at the location (x,y). X X X-- Image dumping functions -------------------------------------------- X XXpwPutImage(<widget>, xdim, ydim, x, y, <vecptr>) X Copies an array onto the window. This is perhaps the most complex X function. xdim and ydim are the x and y dimensions of the array. x X and y are the coordinates where the top left corner of the array X should appear. <vecptr> is the arrayvector of the array. Notice X that the array should be the correct format for the display- X monochrome displays must use one bit deep arrays, with the xdim a X multiple of eight. Color displays can cope with any dimensions, X but notice that the colormap will probably have to be set X properly. X X A typical call might be: X XpwPutImage(w, 512, 512, 10,10, arrayvector(pic1)); X X X-- Window functions --------------------------------------------------- X XXpwClearWindow(<widget>) X Clears the window associated with <widget> X XXpwRestoreWindow(<widget>) X Refreshes the contents of the window. X X-- Colormap operations ------------------------------------------------ X XXpwAllocColorRange(<widget>,num_cells, r1,g1,b1,r2,g2,b2) -> pixelvalue X Allocates a new colour range in the colormap, with the (integer X 0-255) RGB values specified as the start and end colours for the X range, and with num_cells of the colormap allocated. Returns a pixel X value which indicates where in the colormap the set of colors start X XXpwAllocColor(<widget>r1,g1,b1) -> pixelvalue X As for XpwAllocColorRange, but only for one color. X XXpwSetPixel(<widget>,pixel,red,green,blue) X Changes the color entry in the colormap for the pixel to the X specified RGB. X XXpwSetColor(<widget>,<string:name>) X Sets the foreground colour of the widget to the named colour, which X is retrieved from the colour database. See HELP *XpwPopMethods X XXpwSwitchColormaps(<widget>) -> <boolean>; X<boolean> -> XpwSwitchColormaps(<widget>); X If set to true, the widget will perform its own colormap switching. This X is useful if the window manager does not perform colormap switching. The X default value is false. Colormaps should be switched when the mouse X enters the window. X X-- Functions that return (integer) values about the display ----------- X XXpwWidth(<widget>,1,false) X Returns the width of the window of the widget. X XXpwHeight(<widget>,1,false) X Returns the height of the window of the widget. X XXpwDepth(<widget>,1,false) X Returns the depth (num of planes) of the window of the widget. X XXpwScreenWidth(<widget>,1,false) X Returns the width of the screen in pixels. X XXpwScreenHeight(<widget>,1,false) X Returns the height of the screen in pixels. X X-- Functions that alter the Graphics Context -------------------------- X X XThe graphics context contains information about the line style, the Xforeground and background colours, the current font and the drawing mode Xthat is used. These values can be set using xt_value, specifying the Xresource as named in REF *PopGraphic. The following functions are Xprovided as a convenience: X XXpwLineWidth(<widget>) -> <integer> X<integer> -> XpwLineWidth(<widget>) X Changes or returns the width of lines drawn on the window associated X with the widget. X XXpwDrawFunction(<widget>) -> <integer> X<integer> -> XpwDrawFunction(<widget>) X Changes or returns the drawing function used. <integer> here is a X valid X draw function, as described in 'Draw Functions' below. X XXpwForeground(<widget>) -> <integer> X<integer> -> XpwForeground(<widget>) X Changes the foreground color of the widget to the specified pixel X colour. X XXpwBackground(<widget>) -> integer X<integer> -> XpwBackground(widget) X Same as foreground X XXpwSetFont(<widget>,string) -> <boolean> X Changes the current font. Returns <true> if it succeeds, and <false> X if it fails. X X X-- Draw Functions ----------------------------------------------------- X XLib PopGraphic defines constants for all the X windows draw Xfunctions (as used by -XpwDrawFunction- above) as follows: X X GXclear X GXand X GXandReverse X GXcopy X GXandInverted X GXnoop X GXxor X GXor X GXnor X GXequiv X GXinvert X GXorReverse X GXcopyInverted X GXorInverted X GXnand X GXset X X X-- Related Documentation ---------------------------------------------- X XHELP *xt_graphic - for a higher level POP11 interface, XHELP *xt_pwm - PWM compatibility routines X END_OF_FILE if test 6681 -ne `wc -c <'doc/help/PopGraphic'`; then echo shar: \"'doc/help/PopGraphic'\" unpacked with wrong size! fi # end of 'doc/help/PopGraphic' fi if test -f 'doc/help/PopPixmap' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/help/PopPixmap'\" else echo shar: Extracting \"'doc/help/PopPixmap'\" $301 characters$ sed "s/^X//" >'doc/help/PopPixmap' <<'END_OF_FILE' XHELP PopPixmap Jonathan Meyer, Mar 1990 X XPoplog Widget Set, revision 3. X XThe PopPixmap widget is a member of the Poplog Widget Set. For more Xinformation see HELP *PopWidgets, and REF *PopPixmap. For information on Xthe Pop-11 interface to PopPixmap widgets, see HELP *PopGraphic. END_OF_FILE if test 301 -ne `wc -c <'doc/help/PopPixmap'`; then echo shar: \"'doc/help/PopPixmap'\" unpacked with wrong size! fi # end of 'doc/help/PopPixmap' fi if test -f 'doc/help/PopScrollText' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/help/PopScrollText'\" else echo shar: Extracting \"'doc/help/PopScrollText'\" $5401 characters$ sed "s/^X//" >'doc/help/PopScrollText' <<'END_OF_FILE' XHELP *PopScrollText DRAFT - INCOMPLETE Jonathan Meyer, Jan 1990 X XPoplog Widget Set, revision 3. X XThis file describes the Pop-11 interface to the PopScrollText widget Xclass. For details of the PopScrollText widget, see REF *PopScrollText. XFor information on other widgets in the Poplog Widget Set, see HELP X*PopWidgets. X X X CONTENTS - (Use <ENTER> g to access required sections) X X -- Introduction X -- Procedures for PopScrollText Widgets X -- Resource Access X X X-- Introduction ------------------------------------------------------- X X XThe PopScrollText widget was primarliy designed to simplify the transfer Xof VED to X windows. The widget understands a number of basic text Xoperations, which it translates into Xlib calls to manipulate the Xcontents of a window. Operations include scrolling text, displaying Xtext, getting input, and processing events. X XThe PopScrollText widget has very specific low level functionality, and Xmost applications will probably use higher level Text widgets, such as Xthe one described in HELP *PopText. X X-- Loading the PopScrollText Widget ----------------------------------- X XThe Pop-11 interface to the PopScrollText is called LIB *PopScrollText. XThis library does several things: X X1) loads the PopScrollText and PopCore widget classes, if necessary. X X2) loads the external procedure XpwPopCallMethod, for accessing methods X understood by the PopScrollText widget. X X3) defines a set of procedures, written using XpwPopCallMethod and X XpwSetValues, to provide an error-checking interface to the widget. X XThis document concentrates on the Pop-11 procedures defined in (3). X X-- Procedures for PopScrollText Widgets ------------------------------- X XThe following procedures are declared in LIB *PopScrollText: X XXpwTextClearLines(w,l1,l2); X Clears the lines between l1 and l2 of PopScrollText widget w. X XXpwTextClearTail(w,r,c); XXpwTextClearTails(w, l1,l2,c); X Clears all of the characters after column c of PopScrollText X widget w. The second form clears the tails of lines between l1 and X l2, whereas the first form clears the tail of the single line r. X XXpwTextScroll(w, l1, l2, dist); X Moves the text between lines l1 and l2 by distance dist. Dist is X a positive or negative integer, so to scroll the PopScrollText X widget w up by one line, use: X XpwTextScroll(w, 0, XpwTextNumLines(w), -1); X X XXpwTextMoveTail(w, r, c, dist); X Moves the text on row r, after column c by distance dist for X PopScrollText widget w. Distance is measured in characters, and X can be positive or negative. To move a whole line left by one X character, use: X XpwTextMoveTail(w, line, 0, -1); X XXpwTextMoveTails(w,l1,l2,c, dist); X Moves the text on lines between l1 and l2, after column c, by X distance dist. Distance is measured in characters, and can X be positive or negative. To move all of the text in a window X right by one character, for PopScrollText widget w, use: X XpwTextMoveTails(w, 0, XpwTextNumLines(w), 0, 1); X XXpwTextInsert(w, r, c, string); X Inserts the string at row r, column c of PopScrollText widget w. X Text on that row and column will be moved right to make room for the X string. X XXpwTextOverwrite(w, r, c, string); X Draws the string on row r, column c of PopScrollText widget w. X Text previously at that location will be overwritten. X XXpwTextOverwriteLines(w, start_line, strings); X Takes a PopScrollText widget, an array of strings, and a X start line. Overwrites the text on lines starting at start_line X with strings in array. Any line with text drawn on it will be X cleared first. X XXpwTextCursorTo(w, r, c); X Moves the text cursor for the PopScrollText widget w to X row r, column c. X XNOTE: Any of the above procedures can cause exposure events, if text Xthat was previously obscured by a window becomes visible after Xscrolling, or text insertion. X X X-- Resource Access ---------------------------------------------------- X X XXpwSetFont(w, name) -> result; X Takes a Poplog widget and a font name, and tries to load the X font. If the XLoadFont is successful, the fonts ID is returned. X Otherwise returns false. <name> can also be a font ID number, X in which case XpwSetValues is used to set the font resource of X the widget w. X X XXpwTextMargin(w) -> val; X val -> XpwTextMargin(w); X Sets or retreives the left hand margin of the text widget w. X Default value for this margin is 2. If the margin is changed X then the exposure callback is used to tell the application to X redraw the text in the widget. X XXpwTextFontWidth(w) -> val; XXpwTextFontHeight(w) -> val; X The font width and height are calculated in pixels from the X XFontStruct information held in the widgets 'font' resource. X These two procedures return the size of the current font for X PopScrollText widget w. X X XXpwTextNumRows(w) X num -> XpwTextNumRows(w); X Returns or sets the number of rows in the widget w. The updater X form will cause a ResizeRequest to resize the widget. Resizing X the widget will cause an exposure event. X XXpwTextNumColumns(w) X num -> XpwTextNumColumns(w); X Returns or sets the number of columns in the PopScrollText X widget w. Resizes the widget if necessary. X XXpwTextExposedLines(w) X Returns an array of short integers for the PopScrollText widget w. X Each element of the array corrosponds to one line of text in w. X The elements of the array are set according to which lines of X text need refreshing after an exposure event. See REF *PopScrollText X for more information. END_OF_FILE if test 5401 -ne `wc -c <'doc/help/PopScrollText'`; then echo shar: \"'doc/help/PopScrollText'\" unpacked with wrong size! fi # end of 'doc/help/PopScrollText' fi if test -f 'doc/help/PopWidgets' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/help/PopWidgets'\" else echo shar: Extracting \"'doc/help/PopWidgets'\" $7446 characters$ sed "s/^X//" >'doc/help/PopWidgets' <<'END_OF_FILE' XHELP POPWIDGETS Jonathan Meyer, Jan 1990 X XPoplog Widget Set for X11, revision 3. X X XThis document provides an overview of the Poplog Widget Set. For more Xinformation on individual widgets, see the Related Documentation listed Xbelow. X X X CONTENTS - (Use <ENTER> g to access required sections) X X -- Introduction X -- The Poplog Widget Tree X -- The PopCore Widgets X -- Loading Poplog Widget Set X -- Related Documentation X X X-- Introduction ------------------------------------------------------- X XThe X Toolkit provides a C-based object orientated library. The library Xis based around two things: X X 1. The Intrinsics X 2. Widget Sets X X1. Intrinsics X XThese are a set of procedures for manipulating and controlling the Xtoolkit. They contain procedures to initialize the toolkit, create Xtoolkit objects (called widgets), control the widgets during their Xlifetime, and destroy them. Look at HELP * XTOOLKIT, HELP *XT_WIDGETS, Xand the other helpfiles starting with XT in * XPOP_INDEX. X X2. Widget Sets X XWidgets are the graphics objects that are manipulated by the Toolkit. XThey each belong to a class, and have a set of properties. Widget Xproperties include resources, actions, translation tables, and a set of Xprocedures for performing other operations on the widget (such as Xresizing it, or destroying it). Typical widgets are text editors, Xscrollbars, buttons, menues etc. A Widget Set is a collection of widgets Xthat all have the same "look and feel" and similar programmer Xinterfaces. Widget Sets are available from the OSF (Motif), Sony, XHewlett Packard (Xw), Sun, AT&T and others. Currently only the Athena Xwidget set (Xaw) is officially part of the X11R3 release. X X-- The Poplog Widget Tree --------------------------------------------- X XThe Poplog Widget Set was designed to provide an interface between X XWindows and Poplog. It is written in C and externally loaded into Poplog. XIt contains two types of widgets: (1) the PopCore widget class and its Xdescendants, and (2) a few additional widget classes which are subclasses Xof Athena or X Toolkit widgets. X X1) The PopCore widget tree contains a number of widgets which are at a X"medium" level. They are at a higher level than the fundamental toolkit Xwidgets, or raw X Windows, but they are at a much lower level than Xwidgets like ScrollBar or AsciiString, since they are not designed for a Xspecific purpose. They have a large number of resources, which the user Xcan specify. Each widget responds to a set of methods, and uses Xcallbacks - a mechanism allowing the programmer to "trap" events that he Xis interested in. This interface is much easier to program than raw XXlib. X X2) There are currently two additional widget classes in the Poplog XWidget Set: PopComposite and PopText. These widgets inherit all of the Xbehaviour of their superclasses (Composite and AsciiString respectively) Xbut add additional callback actions. These callbacks are used to notify Xapplications of events such are the widget being resized, or a button Xbeing pressed. These widgets may not appear in future releases of the XPoplog Widget Set. X XThe Poplog widgets are arranged in a hierarchy. For example, the XPopGraphic widget class is below the PopPixmap widget class, which is Xin turn below the PopCore widget class in the hierarchy. Because of Xthis, any graphics widgets will inherit all the properties of Pixmap XWidgets and PopCore widgets. The graphics widget uses the Pixmap widgets Xproperties (ie. the pixmap) to store a copy of the contents of the Xwindow. X XThe Widget Hierarchy is broken into two parts: The PopCore part is the Xstem of the main Poplog widget set, but the two additional widgets are Xjust specialisations of already existing widget classes. X XThe Hierarchy looks like this: X X X Composite --------> PopComposite X / ^^^^^^^^^^^^ X / X / / PopScrollText X / / ^^^^^^^^^^^^^ XCore ---{-- PopCore --------{ X \ ^^^^^^^ \ X \ \ PopPixmap --------> PopGraphic X \ ^^^^^^^^^ ^^^^^^^^^^ X (Athena widget set) X \ X Text ----------> AsciiString --------> PopText X ^^^^^^^ X X XThe Poplog Widgets in this hierarchy are designed to be used in addition Xto other widgets, such as the MOTIF widget set, or the ATHENA widget Xset. X X X-- The PopCore Widgets --------------------------------------------------- X X XMethods X XThe PopCore widget and its descendants have a special interface mechanism Xcalled 'methods' that allow relevant procedures for those widgets to be Xaccessed from a single C procedure. This reduces the number of external Xprocedures that have to be loaded within Poplog. For more information about Xthe method system, see SYSDOC *PopWidgets.imp and REF *XpwMethods. X XNaming Conventions X XThe PopCore widgets follow the Athena Widget set naming convents, except that Xall of the procedures relating to the widget set start with the root 'Xpw' Xinstead of 'Xt' or 'Xaw'. For example, the method access procedure is called XXpwCallMethod. Method Identifiers are called XpwM<name>. X X-- Loading Poplog Widget Set ------------------------------------------ X XThe Poplog Widgets can be loaded in Poplog using the LIB *xt_load_wc system. XHowever, the recommended way of loading the Widgets is via a group of Xlibrary packages: X X X LIB *PopCore - loads the PopCore widget class. X X LIB *PopPixmap - loads the PopPixmap widget class. X X LIB *PopGraphic - loads the PopCore, PopPixmap and PopGraphic X widget classes. X X LIB *PopScrollText - loads the PopCore and PopScrollText widget X classes. X X LIB *PopComposite - loads the PopComposite widget class. X X LIB *PopText - loads the Text, AsciiString and PopText widget X classes. X X LIB *PopWidgets - loads all of the above libraries. This is a X more efficient method than loading each X library in turn. X XEach library package uses xt_load_wc to load the requested widgets, Xand then defines a group of Pop-11 procedures that act as the Poplog Xinterface to those widgets. For information about using the widgets, see Xthe relevant documenation listed below. X X X-- Related Documentation ---------------------------------------------- X XThere are two main sources of documentation regarding the Poplog Widget XSet: X X1) A set of REF files describes each of the widgets in the Set: X X REF *PopCore X REF *PopPixmap X REF *PopGraphic X REF *PopScrollText X REF *PopComposite X REF *PopText X X2) A related set of HELP files describes using more general terms the XPop-11 library packages that are used in conjunction with the widgets: X X HELP *PopGraphic - graphics utilites using PopPixmap/PopGraphic. X HELP *PopScrollText - text manipulation using PopScrollText. X HELP *PopComposite - Composite widget manipulation using callbacks. X HELP *PopText - a simple text editor that interacts with Poplog. X XAdditional documentation includes: X X SYSDOC *PopWidgets.imp - discusses some implementation details of X the Poplog Widget Set. X X HELP *PopWidgets.news - latest developements and changes. X X HELP *PopWidgets.index - pointers to help files. X X REF *XpwMethods - index of Poplog Widget methods X X REF *XpwResources - index of Poplog Widget resources END_OF_FILE if test 7446 -ne `wc -c <'doc/help/PopWidgets'`; then echo shar: \"'doc/help/PopWidgets'\" unpacked with wrong size! fi # end of 'doc/help/PopWidgets' fi if test -f 'doc/help/PopWidgets.news' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/help/PopWidgets.news'\" else echo shar: Extracting \"'doc/help/PopWidgets.news'\" $1659 characters$ sed "s/^X//" >'doc/help/PopWidgets.news' <<'END_OF_FILE' XHELP POPWIDGETS.NEWS Jonathan Meyer, Jan 1990 X XThis is Revision 3 of the Poplog Widget Set. Changes since the previous Xrevisions include: X XSoftware changes X X o Graphics Context fields are now resources of PopPixmap. X These work using resource subparts and the {Get,Set}Values_hook X X o Rationalized all resources, modified SetValue procs to do more checks X renamed actions to comply with Intrinsics naming conventions. X X o Added "Methods" to Poplog widgets so that graphics/text procedures X are called using XpwCallMethod (see HELP *XpwMethods) X X o Made methods use hashing tables for faster access X X o Numerous bug fixes for the PopScrollWidget class (ie. make it work!) X X o Made PopText a subclass of AsciiText instead of a modified text X widget X X o Several new methods. Better colour handling - PopAllocColorRange X PopCreateColormap, etc. X X o Caches for fonts, colours and cursors, for PopCore and subclasses. X X XStructural changes X X o Changed file names so that they are 14 character long (for SysV) X X o Simplified Makefile (it's still not perfect) X X o Introduced the Imake mechanism X X o Reorganised the file/directory structure X X XThings still to do X X o Some form of rigerous testing X X o Additional utilities and drawing functions above and beyond Xlib X X o Complete Documentation on internal workings of widget set X X o Selections for PopScrollText widgets X X o Generic widgets? X XFor more information, see: X X HELP *PopWidgets, X HELP *PopGraphic, *PopText, *PopScrollText, XpwMethods. X SYSDOC *PopWidgets.imp X END_OF_FILE if test 1659 -ne `wc -c <'doc/help/PopWidgets.news'`; then echo shar: \"'doc/help/PopWidgets.news'\" unpacked with wrong size! fi # end of 'doc/help/PopWidgets.news' fi if test -f 'doc/ref/PopComposite' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/ref/PopComposite'\" else echo shar: Extracting \"'doc/ref/PopComposite'\" $3912 characters$ sed "s/^X//" >'doc/ref/PopComposite' <<'END_OF_FILE' XREF *PopComposite Jonathan Meyer, Jan 1990 X XPoplog Widget Set, revision 3. X X XThis file describes the PopComposite widget class, which is part of the XPoplog Widget Set. For details of other widgets in the Poplog Widget XSet, see HELP *PopWidgets. For information about the Pop-11 interface to Xthe PopComposite widget, see HELP *PopComposite. X X CONTENTS - (Use <ENTER> g to access required sections) X X -- PopComposite Widget X -- PopComposite Resources X -- Resource Notes X -- Actions and Translations X X-- PopComposite Widget ------------------------------------------------ X XSuperclass: Composite. X XThe PopComposite Widget class is similar to PopCore, in that it adds a Xcallback to an existing widget class, in this case the Composite widget. XThe PopComposite widget uses the callback to notify applications when Xevents (like adding children, or resizing) occur. The PopComposite widget Xis used to manage a set of other widgets, called children. Programmers Xuse the callback to calculate the geometry of all the children of the widget. XUnlike the Form widget, no specification technique for widget location is used. XBy default, all geometry requests are accepted. X XBecause the PopComposite widget notifies applications of resize events, Xand the applications have access to the children of the widget, complex Xgemoetry and location calculations for children of the widget can be Xperformed within the callback. X X-- PopComposite Resources --------------------------------------------- X XThe following resources are retrieved from the argument list or the resource Xdatabase when PopComposite widgets are created. X X=============================================================================== XName Class RepType Default* Description X=============================================================================== XXtNwidth Width Dimension 200 Window width XXtNheight Height Dimension 100 Window height XXtNx X Position 0 X coordinate in pixels XXtNy Y Position 0 Y coordinate in pixels XXtNborderWidth BorderWidth Dimension 1 Border width in pixels XXtNborderPixmap BorderPixmap Pixmap None Window border pixmap XXtNborderColor BorderColor Pixel foreground Window border color XXtNbackground Background Pixel XtDefault Window background color XXtNtranslations Translations String see below Event-to-action translations XXtNpopCallback Callback Pointer NULL Callbacks for events XXtNdestroyCallback Callback NULL XtDestroyWidget callback XXtNmappedWhenManaged Boolean TRUE automatic XtMapWidget X X* default values listed as XtDefault are in fact set to the string X XtDefault<Class> where Class is the class name of that resource, eg. X 'XtDefaultForeground', 'XtDefaultFont' etc. X X X-- Resource Notes ------------------------------------------------------------- X XThe following notes describe new resources or properties of resources for XPopComposite widgets. X XXtNpopCallback X This callback list is used notify clients of events. See below. X XXtNpointerShape X This resource defines the cursor that should be displayed when the pointer X is in the window of the widget. Applications can create a cursor (using X XCreateFontCursor for example), and then set this resource. Setting this X resource causes an XDefineCursor call, unless the new cursor that is X specified is NULL, in which case XUndefineCursor is used instead. X X X-- Actions and Translations ------------------------------------------- X X XPopComposite has one action: NotifyConfigureEvent. It has one default XTranslation: X X "<Configure>: notify-configure-event()\n" X XThe notify-configure-event action calls the XtNpopCallback list. Configure Xevents include resize events and adding children. END_OF_FILE if test 3912 -ne `wc -c <'doc/ref/PopComposite'`; then echo shar: \"'doc/ref/PopComposite'\" unpacked with wrong size! fi # end of 'doc/ref/PopComposite' fi if test -f 'doc/ref/PopCore' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/ref/PopCore'\" else echo shar: Extracting \"'doc/ref/PopCore'\" $12566 characters$ sed "s/^X//" >'doc/ref/PopCore' <<'END_OF_FILE' XREF *PopCore Jonathan Meyer, Jan 1990 X XPoplog Widget Set, revision 3. X XThis file describes the PopCore widget class, which is part of the XPoplog Widget Set. For details of other widgets in the Poplog Widget XSet, see HELP *PopWidgets. For information about the Pop-11 interface to Xthis widget, see HELP *PopCore. X X X CONTENTS - (Use <ENTER> g to access required sections) X X -- PopCore Widget X -- PopCore Resources X -- Resource Notes X -- Further Notes X -- Actions X -- Translations X -- Methods X X-- PopCore Widget ----------------------------------------------------- X XSuperclass: Core X XThe PopCore widget is similar to the Core widget class but with more Xresources, and a callback list that is activated through an action. You Xcan specify the events that the callback is activated on using the Xtranslation table. The PopCore widget has a Graphics Context, which is Xused to hold resources like line width, line style, foreground and Xbackground colours etc. This graphics context is used by subclasses of the XPopCore widget class in graphics and text operations. X XThe PopCore widget class is intended as a base for building more Xsophisticated widget classes. As such, it is probably of limited use to Xapplications, which will probably use subclasses of PopCore, such as the XPopGraphic widget class. X XThe class variable for the PopCore widget is popCoreWidgetClass. X X-- PopCore Resources ---------------------------------------------------------- X XThe following resources are retrieved from the argument list or the resource Xdatabase when PopCore widgets are created. X X=============================================================================== XName Class RepType Default* Description X=============================================================================== XXtNwidth Width Dimension 200 Window width XXtNheight Height Dimension 100 Window height XXtNx X Position 0 X coordinate in pixels XXtNy Y Position 0 Y coordinate in pixels XXtNborderWidth BorderWidth Dimension 1 Border width in pixels XXtNborderPixmap BorderPixmap Pixmap None Window border pixmap XXtNborderColor BorderColor Pixel foreground Window border color XXtNbackground Background Pixel XtDefault Window background color XXtNforeground Foreground Pixel XtDefault Window foreground color XXtNfont Font FontStruct XtDefault Font for text operations XXtNpointerShape Cursor Cursor None mouse cursor(cursorfont) XXtNtranslations Translations String see below Event-to-action translations XXtNpopCallback Callback Pointer NULL Callbacks for events XXtNautoFlush Boolean Boolean TRUE XFlush after methods? XXtNusersGC GC Pointer NULL Graphics Context for ops XXtNmodifiers Parameter Int None event->state modifiers XXtNdestroyCallback Callback NULL XtDestroyWidget callback XXtNmappedWhenManaged Boolean TRUE automatic XtMapWidget X X* default values listed as XtDefault are in fact set to the string X XtDefault<Class> where Class is the class name of that resource, eg. X 'XtDefaultForeground', 'XtDefaultFont' etc. X X X-- Resource Notes ------------------------------------------------------------- X XThe following notes describe new resources or properties of resources for XPopCore widgets. X X XXtNwidth, XtNheight X Changing a widgets width or height resource will cause a Resize request. X XXtNforeground, XtNbackground X foreground and background can be changed using XtSetValues. This causes X an XChangeGC on the users GC. Valid pixel values must be provided. X XXtNautoFlush X This resource is inspected after calling a Poplog Widget Method. (See X REF *XpwCallMethod, REF *XpwMethods for more). If its value is TRUE, X an XFlush is issued. By setting it FALSE, users can perform several X method calls at once. When the resource is set to TRUE, XFlush is X called. The following code fragment shows how autoFlush can be used: X X XtSetValue(widget, XtNautoFlush, FALSE); X X /* put multiple method calls inside "autoFlush" brackets */ X i = 100; X while (i--) X XpwCallMethod(widget, XpwMDrawPoint, random(100),random(100)); X X XtSetValue(widget, XtNautoFlush, TRUE); X X Setting this resource TRUE increments an internal counter. Setting it X FALSE decrements the counter. An XFlush is only performed if the counter X has reached 0. X XXtNpointerShape X This resource defines the cursor that should be displayed when the pointer X is in the window of the widget. Applications can create a cursor (using X XCreateFontCursor for example), and then set this resource. Alternatively, X they can use the XpwMSetCursor method (see below). Setting this resource X causes an XDefineCursor call, unless the new cursor that is specified is X NULL, in which case XUndefineCursor is used instead. X XXtNfont X This resource is a pointer to an XFontStruct. Applications can load their X own fonts, using XLoadQueryFont, and then set this resource. Alternatively, X they can use the XpwMSetFont method (see below). All subclasses of PopCore X use this font as their main/default font, although they may supplement it X with additional fonts. Setting this resource modifies the usersGC resource. X XXtNusersGC X This resource holds a pointer to the widgets graphics context (GC). X Subclasses of PopCore all use the 'usersGC' held in the PopCore part X of the widget structure to perform their graphics and text operations. X Subclasses provide resources for altering relevant parts of the GC values. X The PopCore widget provides foreground, background and font resource for X this purpose. See Xlib Programming Manual, vol. 1, Ch. 6 for more on GC's. X Changing 'usersGC' will cause the previous GC to be released. X XXtNmodifiers X This is set to event->state after any events in the widgets window. X This resource reflects the modifiers (shift, ctrl, meta) etc. which are X in use when the event occured. Event handlers are expected to need this X information. X X X-- Further Notes ----------------------------------------------------------- X XThe Users Graphics Context X XThe usersGC resource has many other derived resources relating to it, Xincluding foreground, background, font, and others. X XThe PopCore widget tries to minimise the number of XChangeGC calls. XUsing XtSetValues to set more than one graphics context field resource at Xonce is much more efficient than changing one resource at a time. X XThe PopCore widget also tries to share the usersGC. If you create Xmany widgets which all have the same graphics context values, they will all Xshare the same GC. Using XtSetValues to change fields in a usersGC Xfor a widget will cause that widget to release its shared graphics context Xand use a unique one. For this reason, you should not modify the usersGC Xdirectly unless you are sure that it is no longer a shared GC. You can Xensure this by changing one of the fields of the GC using XtSetValues before Xusing Xlib routines to change other fields in the GC. X XFor more resources derived from the usersGC, see REF *PopPixmap. X X-- Actions --------------------------------------------------------------- X XThe PopCore widget class has one action, called "notify-event", that Xcalls the XtNpopCallback list. X X-- Translations ----------------------------------------------------------- X XThe PopCore widget does not perform any event processing in its translation Xtable. This is left to the programmer - widgets below PopCore in the XPoplog Widget Set differentiate events, and call callback lists based on Xevent type. The application could create a PopCore widget with the following Xtranslations: X X "<ResReq>: notify-event() \n\ X <Expose>: notify-event() " X X-- Methods --------------------------------------------------------------- X XPopCore widgets respond to six methods: XpwMSetColor, XpwMFreeColor, XXpwMSetFont, XpwMFreeFont, XpwMSetCursor and XpwMFreeCursor. These methods Xemploy caches so that the application can repeatedly change colors, fonts Xand cursors without expensive calls to the X Server. X XMethod Name Arguments Notes X======================================================================== XXpwMSetColor string either name or #rgb format XXpwMFreeColor string XXpwMSetFont string XXpwMFreeFont string XXpwMSetCursor shape shape in cursorfont.h XXpwMFreeCursor shape eg. XC_crosshair X X XXpwMSetColor X XpwCallMethod(widget, XpwMSetColor, name); X Widget widget; X String name; X X This method is used to set the foreground of a widget to the named color. X It works as follows: if the color cache has not yet been initialized, X a new cache is created, with two entries - XtDefaultForeground and X XtDefaultBackground. The first entry is used if the name string is NULL. X If the name string isn't null, it is converted into a lowercase quark, and X the cache is searched for an entry whose key is that quark. If an entry X does not exist, and a call to XParseColor/XAllocColor is successful, the X returned color is added to the cache. If both attempts to locate the color X fail, the method returns with a result of zero. Otherwise, the method uses X XtSetValues to set the foreground of the widget, and returns with the X new color's pixel value. X XXpwMFreeColor X XpwCallMethod(widget, XpwMFreeColor, name); X Widget widget; X String name; X X PopFreeColor will search the color cache for the named color. If X an entry in the cache exists, the related XColor is released using X XFreeColor, and the cache entry is removed. You cannot free the XtDefault X cache entries -they are always available to XpwMSetColor calls. If you free X a color which is the current foreground of the widget, the method calls X XpwMSetColor to set the foreground of the widget to the default foreground. X XXpwMSetFont X XpwCallMethod(widget, XpwMSetFont, fontname); X Widget widget; X String fontname; X X This method works as follows: if the font cache has not yet been X initialized, a new cache is created, with one entry - XtDefaultFont. X This entry is used if the fontname string is NULL. If the fontname string X isn't null, it is converted into a lowercase quark, and the cache is X searched for an entry whose key is that quark. If an entry does not exist, X and a call to XLoadQueryFont is successful, the returned font is added to X the cache. If both attempts to locate the font fail, the method returns X with a result of zero. Otherwise, the method uses XtSetValues to set the X font of the widget, and the method returns with the font's ID. X XXpwMFreeFont X XpwCallMethod(widget, XpwMFreeFont, fontname); X Widget widget; X String fontname; X X PopFreeFont will search the font cache for a font whose name is fontname. X If an entry in the cache exists, the related XFontStruct is released using X XFreeFont, and the cache entry is removed. You cannot free the XtDefaultFont X cache entry - this font is always available to XpwMSetFont calls. If you X free a font which is the current font for the widget, the method calls X XpwMSetFont to set the font of the widget to the default font. X XXpwMSetCursor X XtPopCallMethod(widget, XpwMSetCursor, shape); X Widget widget; X Cardinal shape; X X XpwMSetCursor first checks to see if the cursor cache exists. If it does X not exist, a new cache is created, with no entries. Otherwise the cache X is searched for the requested cursor shape (XC_crosshair, XC_arrow etc). X If an entry in the cache does not exist, the method calls XCreateFontCursor X to load the requested cursor shape, which is then added to the cache. X Then the method uses XtSetValues to set the pointerShape resource of the X widget. The cursor returned from XCreateFontCursor is returned. X XXpwMFreeCursor X XpwCallMethod(widget, XpwMFreeCursor, shape); X Widget widget; X Cardinal shape; X X This method first checks the cursor cache for an entry corrosponding to X shape. If that entry exists, PopFreeCursor uses XFreeCursor to release the X memory associated with the cursor. If the current cursor for the widget is X the same as shape, XtSetValues is used to set the cursor to the server X default (ie. using XUndefineCursor). END_OF_FILE if test 12566 -ne `wc -c <'doc/ref/PopCore'`; then echo shar: \"'doc/ref/PopCore'\" unpacked with wrong size! fi # end of 'doc/ref/PopCore' fi if test -f 'doc/ref/PopGraphic' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/ref/PopGraphic'\" else echo shar: Extracting \"'doc/ref/PopGraphic'\" $13333 characters$ sed "s/^X//" >'doc/ref/PopGraphic' <<'END_OF_FILE' XREF *PopGraphic Jonathan Meyer, Jan 1990 X X XPoplog Widget Set, revision 3. X XThis file describes the PopGraphic widget class, which is part of the XPoplog Widget Set. For details of other widgets in the Poplog Widget XSet, see HELP *PopWidgets. For details of the Pop-11 interface to the XPopGraphic widget class, see HELP *PopGraphic. X X X X CONTENTS - (Use <ENTER> g to access required sections) X X -- PopGraphic Widget X -- Resources X -- Resource Notes X -- PopGraphic Actions X -- PopGraphic Translations X -- Methods X -- PopGraphic Methods X X X-- PopGraphic Widget --------------------------------------------------- X XSuperclass: PopPixmap X XA PopGraphic widget is a general purpose window. Any of the Xlib Xgraphics primatives can be applied to the widget. Because it is a Xsubclass of PopPixmap, it has a pixmap associated with it, which is Xautomatically set to be the same size as the window. Any graphics Xoperations are duplicated on the pixmap, which is used to restore the Xcontents of the window after resize and exposure events. PopGraphic Xwidgets use callbacks to notify applications of events. They also Xhave colormap manipulation methods. X XThere are a variety of operations that can be performed on Graphics Xwidgets. They are all accessed using the PopCore Method Calling Xinterface. See HELP *PopGraphic and LIB *PopGraphic for Pop-11 Xinterfaces to the methods available to graphics widgets. See XREF *XpwMethods for more information about methods. X XAlthough the PopGraphic widget class is fairy simple, it is also very Xuseful. Programmers can use graphics widgets as general purpose windows Xto display textual or graphical output, without having to worry about Xcomplex details such as (exposure) events and colormaps. X XThe class variable of PopGraphic is popGraphicWidgetClass. X X-- Resources -------------------------------------------------------------- X X XPopGraphic inherits all of the resources of PopCore and PopPixmp. The following Xresources are retrieved from the argument list or the resource database Xwhen PopGraphic widgets are created. X X=============================================================================== XName Class RepType Default* Description X=============================================================================== XXtNwidth Width Dimension 200 Window width XXtNheight Height Dimension 100 Window height XXtNx X Position 0 X coordinate in pixels XXtNy Y Position 0 Y coordinate in pixels XXtNborderWidth BorderWidth Dimension 1 Border width in pixels XXtNborderPixmap BorderPixmap Pixmap None Window border pixmap XXtNborderColor BorderColor Pixel foreground Window border color XXtNbackground Background Pixel XtDefault Window background color XXtNforeground Foreground Pixel XtDefault Window foreground color XXtNfont Font FontStruct XtDefault Font for text operations XXtNpointerShape Cursor Cursor None mouse cursor(cursorfont) XXtNtranslations Translations String see below Event-to-action translations XXtNpopCallback Callback Pointer NULL Callbacks for events XXtNautoFlush Boolean Boolean TRUE XFlush after methods? XXtNusersGC GC Pointer NULL Graphics Context for ops XXtNmodifiers Parameter Int None event->state modifiers XXtNdestroyCallback Callback NULL XtDestroyWidget callback XXtNmappedWhenManaged Boolean TRUE automatic XtMapWidget XXtNfunction Function Int XtDefault GC drawing mode XXtNsubwindowMode SubWindowMode Int XtDefault GC subwindow mode XXtNlineWidth LineWidth Int XtDefault GC line width XXtNlineStyle LineStyle Int XtDefault GC line style XXtNcapStyle CapStyle Int XtDefault GC cap style XXtNjoinStyle JoinStyle Int XtDefault GC join style XXtNprivateGC GC Pointer None Pixmap Graphics Context XXtNpixmap Pixmap Pointer None Pixmap of Widget. XXtNpixmapStatus PixmapStatus Cardinal PixmapOn Is Pixmap active? XXtNusePrivateGC Boolean Boolean TRUE See below XXtNmyGC GC Pointer NULL GC for window refresh XXtNswitchCmaps Boolean Boolean FALSE Automatic cmap install XXtNmouseX MouseLocation Int None Mouse X location in pixels XXtNmouseY MouseLocation Int None Mouse Y location in pixels XXtNbuttonEvent Callback Pointer NULL Called on ButtonPress XXtNkeyboardEvent Callback Pointer NULL Called on KeyPress XXtNmouseEvent Callback Pointer NULL Called on Enter/Leave XXtNmotionEvent Callback Pointer NULL Called on mouse Motion XXrNresizeEvent Callback Pointer NULL Called on Resize Req X X* default values listed as XtDefault are in fact set to the string X XtDefault<Class> where Class is the class name of that resource, eg. X 'XtDefaultLineWidth', 'XtDefaultLineStyle' etc. X X X-- Resource Notes ----------------------------------------------------- X XXtNusePrivateGC X The XtNusePrivateGC resource specifies which of the two available X Graphics Contexts should be used to restore the contents of the window X after an exposure or resize event. X X If 'usePrivateGC' is TRUE, the Graphics Context from the poppixmap part X of the widget is used (ie. 'privateGC'). This GC is set to the default X server GC, and should not be changed. If 'usePrivateGC' is FALSE, the X graphics context from the popcore part of the widget is used (ie. X 'usersGC'). This graphics context can by modified using the GC X resources (see above). The default value is TRUE. The resource 'myGC' X points to the graphics context that is currently being used to restore X the window from the pixmap. This is either 'usersGC' or 'privateGC', but X should not be modified by applications. X X This use of two graphics contexts is designed so that applications can X choose to have changes in the users graphics context affect the appearence X of the overall window after exposure or resize events. For example, altering X the background colour of the usersGC to red would cause the whole window X to become red (assuming usePrivateGC was FALSE). However, many X applications would not want changes to the usersGC to affect the X appearence of the whole window. X X XXtNswitchCmaps X The 'switchCmaps' resource determines whether the graphics widget should X perform its own Colormap switching, if the widget has a different X colormap from the default colormap of the screen. If switchCmaps is X TRUE, the widget will call XInstallColormap to switch to its own X colormap on EnterNotify events, and XUninstallColormap to revert to the X default colormap on LeaveNotify events. Window managers should do this for X the window automatically. Interclient conventions state that windows should X not use XInstall/UninstallColormap. However, the ability to perform colormap X switching can be useful, especially if your favourite window manager does X not perform this operation for you! X X XXtNpixmapStatus X If the PopPixmap resource pixmapStatus is either PixmapOff or PixmapHasNone, X the PopGraphic widget calls the 'popCallback' callback list to notify the X client of exposure events. X XXtNmouseX, XtNmouseY X The 'mouseY' and 'mouseX' resources are set by the widget whenever a X new event occurs. They can be read by the application to determine the X mouse location, in pixels. X X XbuttonEvent, keyboardEvent, mouseEvent, motionEvent, resizeEvent X The *Event resources are Callback Lists. They should not be updated. X Users can add procedures to one of these callback list using X XtAddCallback, specifying which event they are interested in trapping. X See HELP *XT_CALLBACKS for more information. For example, adding foo as X a callback procedure for motionEvents would look something like: X X XtAddCallback(widget, XtNmotionEvent, foo, false) X X Notice that the resources 'mouseX', 'mouseY' and 'modifiers' are set before X a client is notified of an event - clients can read these resources to X determine what action to take. X X-- PopGraphic Actions ------------------------------------------------- X XThe following actions are avaliable for PopGraphic widgets. Actions Xcall their associated callback list with data extracted from the event Xand the arguments to the action. X X Name Event Call Data X ---- ------------------ --------------------- X notify-button-event ButtonPress/Release +/-Button number X notify-keyboard-event Key press +/-Keysym of key X notify-motion-event Mouse Motion Button number, or 0 X notify-mouse-event Mouse Enter/Leave Event type X notify-resize-event Resize request Event type X XA ButtonPress or KeyPress event's call data is positive. A ButtonRelease/ XKeyRelease event's call data is negative. For example, pushing button 3 Xdown will first call XtNbuttonEvent with 3, and then -3. X X X-- PopGraphic Translations -------------------------------------------- X XThe default translations for Graphics widgets is as follows: X X "<BtnDown>: notify-button-event() \n\ X <BtnUp>: notify-button-event() \n\ X <EnterWindow>: notify-mouse-event() \n\ X <LeaveWindow>: notify-mouse-event() \n\ X <Motion>: notify-motion-event() \n\ X <ResReq>: notify-resize-event() \n\ X <KeyPress>: notify-keyboard-event() \n\ X <KeyRelease>: notify-keyboard-event()"; X X-- Methods ------------------------------------------------------------- X XThe PopGraphic widget inherits all of the methods of the PopPixmap Xwidget class, and also adds a few new methods. X XMethod Name Xlib function Args X============================================================ XXpwMDrawArcs XDrawArcs arcs,narcs XXpwMDrawArc XDrawArc x,y,w,h,a1,a2 XXpwMDrawLine XDrawLine x,y,w,h XXpwMDrawLines XDrawLines pts,npts XXpwMDrawPoint XDrawPoint x,y XXpwMDrawPoints XDrawPoints pts,npts XXpwMDrawRectangle XDrawRectangle x,y,w,h XXpwMDrawRectangles XDrawRectangles recs,nrecs XXpwMDrawSegments XDrawSegments segs,nsegs XXpwMFillArc XFillArc x,y,w,h,a1,a2 XXpwMFillArcs XFillArcs arcs,narcs XXpwMFillPolygon XFillPolygon pts,npts,shape,mode XXpwMFillRectangle XFillRectangle x,y,w,h XXpwMFillRectangles XFillRectangles recs,nrecs XXpwMDrawString XDrawString x,y,str,len XXpwMDrawImageString XDrawImageString x,y,str,len XXpwMPutImage XPutImage image,sx,sy,ex,ey,w,h XXpwMGetImage XGetImage x,y,w,h,msk,format XXpwMClearArea XClearArea x,y,w,h XXpwMClearWindow XClearWindow none XXpwMDrawImage - x,y,w,h,data XXpwMCopyFrom - src_widget,x,y,w,h,ex,ey XXpwMCopyTo - dst_widget,x,y,w,h,ex,ey X XFor more details of the arguments used by each graphics primative, see Chapter X6 of the Xlib Programming Manual, vol. 1. Note that GC's, windows and Xdisplays are supplied by the method, and need not be passed as arguments. X XDetails of XpwMDrawImage, XpwMCopyFrom and XpwMCopyTo are in REF *PopPixmap. X X X-- PopGraphic Methods ------------------------------------------------- X X======================================================================== XMethod Name Arguments Notes X======================================================================== XXpwMCreateColormap none sets switchCmaps on. XXpwMFreeColormap none XXpwMAllocColorRange n,r,g,b,r,g,b see below. XXpwMAllocStoreColor r,g,b XXpwMSetPixelColor p,r,g,b X X XXpwMCreateColormap X XpwCallMethod(widget, XpwMCreateColormap) X Widget widget; X X This method calls XCreateColormap to make a new colormap for the X widget. If the call is successful, a non-zero value is returned. X XXpwMFreeColormap X XpwCallMethod(widget, XpwMFreeColormap) X X This method frees the colormap of the widget, and sets the colormap to X the default colormap of the screen. X XXpwMAllocColorRange X XpwCallMethod(widget, XpwMAllocColorRange, num_cells, r1,g1,b1, r2,g2,b2); X Widget widget; X int num_cells, r1,g1,b1,r2,g2,b2; X X This method allocates num_cells entries from the colormap and sets the X cells to the colors starting at one rgb value (r1,g1,b1) progressing X linearly to another rgb value (r2,g2,b2), which should be in the range X 0-255. A simple gray scale can be created using: X X XpwCallMethod(widget, XpwMAllocColorRange, 100, 0,0,0, 255,255,255); X XXpwMAllocStoreColor X XpwCallMethod(widget, XpwMAllocStoreColor, r,g,b) X Widget widget; X int r,g,b; X X Uses XAllocColor and XStoreColor to allocate and store a color cell with X the specified rgb value. X XXpwMSetPixelColor X XpwCallMethod(widget, XpwMSetPixelColor, pixel, r,b,g); X Widget widget; X Pixel pixel; X int r,g,b; X X Sets the read/write pixel to the specified color. END_OF_FILE if test 13333 -ne `wc -c <'doc/ref/PopGraphic'`; then echo shar: \"'doc/ref/PopGraphic'\" unpacked with wrong size! fi # end of 'doc/ref/PopGraphic' fi if test -f 'doc/ref/PopPixmap' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/ref/PopPixmap'\" else echo shar: Extracting \"'doc/ref/PopPixmap'\" $11820 characters$ sed "s/^X//" >'doc/ref/PopPixmap' <<'END_OF_FILE' XREF *PopPixmap Jonathan Meyer, Jan 1990 X XPoplog Widget Set, revision 3. X XThis file describes the PopPixmap widget class, which is part of the XPoplog Widget Set. For details of other widgets in the Poplog Widget XSet, see HELP *PopWidgets. For information about the Pop-11 interface Xto the PopPixmap widget see HELP *PopPixmap. X X-- PopPixmap Widget --------------------------------------------------- X XSuperclass: PopCore. X XMost widgets have a window associated with them. However, the PopPixmap Xwidget is not in this sense a widget, as it does not have an associated Xwindow. Instead it is a way of creating X Pixmaps using the facilities X(eg. resources) of the X Toolkit. Pixmaps are the same as windows, Xexcept that they are never visible to the user. Pixmaps are therefore used Xto contain copies of windows, or to perform cut/paste operations between Xwindows. X XThe PopPixmap widget is intended as the base for widgets that are graphical Xin nature, and its functionality is an important part of the PopGraphic XWidget. It contains resources such as lineWidth and function that are used Xto set and retreive values from the 'usersGC' graphics context. X XX pixmaps are created at widget initialization time. Because class widget XInitialize procedures are super-to-subclass chained, subclasses of XPopPixmap widgets will have pixmaps created for them automatically. X XThe PopPixmap widget has a resource which is used to control the pixmap. XThis allows subclasses and applications to use the methods and resources Xof PopPixmap widgets without also using the pixmap. X XThe PopPixmap realize procedure assigns the pixmap created at Xinitialize to the window slot of the widget structure. X XResizing a PopPixmap widget causes the creation of a new pixmap X(XCreatePixmap) of the specified size. The old pixmaps Xcontents is then copied to the new pixmap (XCopyArea), and the old Xpixmap is released (XFreePixmap). This is expensive, but Xlib does not Xhave an XResizePixmap request. To minimize this, the pixmap is only Xresized when the widget has grown in size. X XDestroying a PopPixmap widget causes its pixmap and graphics context Xresources to be freed. X XThe class variable of PopPixmap is popPixmapWidgetClass. X X-- PopPixmap Resources ------------------------------------------------ X XPopPixmap inherits all of the resources of PopCore. The following Xresources are retrieved from the argument list or the resource database Xwhen PopPixmap widgets are created. X XCore and PopCore resources X X=============================================================================== XName Class RepType Default* Description X=============================================================================== XXtNwidth Width Dimension 200 Window width XXtNheight Height Dimension 100 Window height XXtNx X Position 0 X coordinate in pixels XXtNy Y Position 0 Y coordinate in pixels XXtNborderWidth BorderWidth Dimension 1 Border width in pixels XXtNborderPixmap BorderPixmap Pixmap None Window border pixmap XXtNborderColor BorderColor Pixel foreground Window border color XXtNbackground Background Pixel XtDefault Window background color XXtNforeground Foreground Pixel XtDefault Window foreground color XXtNfont Font FontStruct XtDefault Font for text operations XXtNpointerShape Cursor Cursor None mouse cursor(cursorfont) XXtNtranslations Translations String see below Event-to-action translations XXtNpopCallback Callback Pointer NULL Callbacks for events XXtNautoFlush Boolean Boolean TRUE XFlush after methods? XXtNusersGC GC Pointer NULL Graphics Context for ops XXtNmodifiers Parameter Int None event->state modifiers XXtNdestroyCallback Callback NULL XtDestroyWidget callback XXtNmappedWhenManaged Boolean TRUE automatic XtMapWidget X XPopPixmap resources X X======================================================================= XName Class RepType Default* Description X======================================================================= XXtNfunction Function Int XtDefault GC drawing mode XXtNsubwindowMode SubWindowMode Int XtDefault GC subwindow mode XXtNlineWidth LineWidth Int XtDefault GC line width XXtNlineStyle LineStyle Int XtDefault GC line style XXtNcapStyle CapStyle Int XtDefault GC cap style XXtNjoinStyle JoinStyle Int XtDefault GC join style XXtNprivateGC GC Pointer None Pixmap Graphics Context XXtNpixmap Pixmap Pointer None Pixmap of Widget. XXtNpixmapStatus PixmapStatus Cardinal PixmapOn Is Pixmap active? X X* default values listed as XtDefault are in fact set to the string X XtDefault<Class> where Class is the class name of that resource, eg. X 'XtDefaultLineWidth', 'XtDefaultLineStyle' etc. X X X-- Resource Notes ------------------------------------------------------------- X XThe following notes describe new resources or properties of resources for XPopPixmap widgets. X X XXtNfunction XtNsubwindowMode XtNlineWidth XXtNlineStyle XtNcapStyle XtNjoinStyle X The first 6 PopPixmap resources are slots in the 'usersGC' Graphics Context. X Changing the 'function' resource of a PopPixmap widget is in fact the same X as calling XChangeGC to modify the function slot of the usersGC. String X converters are provided, so that valid values for each of these resources X can be specified in a resource file that is read by xrdb(1). For more on X Graphics Contexts, see the Xlib Programming Manual, vol 1, Chapter 5. X XXtNpixmap X The 'pixmap' resource can be modified. Changing this resource causes an X XFreePixmap call to release the previous pixmap. A valid Pixmap must be X used if this resource is updated. This may have strange side effects, X since the width and height of the widget will become out of sync with the X width and height of the pixmap. X XXtNpixmapStatus X A PopPixmap widget's pixmap can be in one of three states: PixmapOn X is the default normal state, PixmapOff indicates that the widget X has a valid pixmap, but any methods applied to the widget will have X no effect to the pixmap, and PixmapHasNone indicates that the widget does X not have a valid pixmap. Changing from PixmapHasNone to PixmapOn causes X an XCreatePixmap request. Changing from PixmapOn to PixmapHasNone frees the X current Pixmap. Changing to PixmapOn also causes the widgets redisplay X procedure to be called. X XXtNprivateGC X The 'privateGC' resource should not be modified. It is a server default X graphics context, and is used by subclasses of PopPixmap to copy pixmaps X to windows. Applications may fetch this resource if they wish to use X a default graphics context for some operation. X XActions and Translations X XPopPixmap widgets do not have any actions, or translation tables. Events Xcannot occur on pixmaps, so the notion of events is not useful. X XMethods X XPopPixmap widgets respond to all of the Xpw equivelants of the Xlib Xgraphics operations: X X======================================================================== XMethod Name Xlib Procedure Arguments X======================================================================== XXpwMDrawArc XDrawArc x,y,w,h,a1,a2 XXpwMDrawArcs XDrawArcs arcs,narcs XXpwMDrawLine XDrawLine x,y,w,h XXpwMDrawLines XDrawLines pts,npts XXpwMDrawPoint XDrawPoint x,y XXpwMDrawPoints XDrawPoints pts,npts XXpwMDrawRectangle XDrawRectangle x,y,w,h XXpwMDrawRectangles XDrawRectangles recs,nrecs XXpwMDrawSegments XDrawSegments segs,nsegs XXpwMFillArc XFillArc x,y,w,h,a1,a2 XXpwMFillArcs XFillArcs arcs,narcs XXpwMFillPolygon XFillPolygon pts,npts,shape,mode XXpwMFillRectangle XFillRectangle x,y,w,h XXpwMFillRectangles XFillRectangles recs,nrecs XXpwMDrawString XDrawString x,y,str,len XXpwMDrawImageString XDrawImageString x,y,str,len XXpwMPutImage XPutImage image,sx,sy,ex,ey,w,h XXpwMGetImage XGetImage x,y,w,h,msk,format XXpwMDrawImage - w,h,x,y,data,depth XXpwMClearArea XClearArea x,y,w,h XXpwMClearWindow - none XXpwMCopyFrom - src_widget,x,y,w,h,ex,ey XXpwMCopyTo - dst_widget,x,y,w,h,ex,ey X XAll except the last four of the PopPixmap methods are identical to their Xlib Xcounterparts, except that they take a widget instead of a window. They all Xuse the widget's display, usersGC and pixmap, as required, in calls to Xtheir related Xlib functions. For example, to draw a line on a PopPixmap Xwidget p, use: X X XpwCallMethod(p, XpwMDrawLine, 1,1,100,100); X XFor more details of the arguments used by each graphics primative, see Chapter X6 of the Xlib Programming Manual, vol. 1. X X XDetails of XpwMDrawImage, XpwMCopyFrom and XpwMCopyTo are given below: X XXpwMCopyFrom X XpwCallMethod(wid, XpwMCopyFrom, src_wid,x,y,w,h,ex,ey); X Widget wid, src_wid; X int x,y,w,h,ex,ey; X X This method parallel's the Xlib XCopyArea function. The method takes X a source widget src_wid, and copies the area within the rectangle (x,y,w,h) X from the source widget to (ex,ey) in the pixmap widget wid. If w or h X are zero, the width and height of the src_wid are used. If X src_wid is NULL, then wid is used as both the source and the X destination of the XCopyArea function. wid must be a PopPixmap widget, X or a subclass of a PopPixmap widget. X XXpwMCopyTo X XpwCallMethod(wid, XpwMCopyTo, dest_wid, x,y,w,h,ex,ey); X Widget wid, dest_wid; X int x,y,w,h,ex,ey; X X This method parallel's the Xlib XCopyArea function, and is similar to X the XpwMCopyFrom method. The method takes a destination widget dest_wid, X and copies the area specified by the rectangle (x,y,w,h) of the pixmap X of wid to ex,ey of the window of dest_wid. If w or h X are zero, the width and height of the widget wid are used. If X dest_wid is NULL, then wid is used as both the source and the X destination of the XCopyArea function. wid must be a PopPixmap widget, X or a subclass of a PopPixmap widget. X XXpwMDrawImage X XpwCallMethod(widget, XpwMDrawImage,w,h,x,y,data,depth) X Widget widget; X int x,y,w,h,depth; X char *data; X X This method takes a pointer to some data, and a size width/height (w/h) of X the image that is held in the data. It uses XCreateImage to construct X an image of the specified size, using the specified data, which is X expected to be in the right format for the visual class of the screen X of the widget (ie. ZPixmap for color and XYPixmap for mono screens). X This image is then copied to the pixmap of the PopPixmap widget at x,y, X using XPutImage. Finally, the XImage structure is released using X XDestroyImage. X X XResource Converters X XNew resource converters are registered to convert between the graphics Xcontext fieldname strings, and their values, and for XtNpixmapStatus resources. XFor example, a possible resource table entry for the XtNfunction resource is: X X Draw*function: xor X XPossible values for each resource (with the default given last) are: X Xfunction: X X clear and andReverse andInverted noop xor or nor equiv invert X orReverse set copyInverted orInverted nand copy X XsubwindowMode: X X IncludeInferiors ClipByChildren X XcapStlye: X X NorLast Round Projecting Butt X XjoinStyle: X X Bevel Round Miter X XlineStyle: X X OnOffDash DoubleDash Solid X XpixmapStatus: X X PixmapOn PixmapOff PixmapHasNone END_OF_FILE if test 11820 -ne `wc -c <'doc/ref/PopPixmap'`; then echo shar: \"'doc/ref/PopPixmap'\" unpacked with wrong size! fi # end of 'doc/ref/PopPixmap' fi echo shar: End of archive 1 $of 2$. cp /dev/null ark1isdone MISSING="" for I in 1 2 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked both archives. rm -f ark[1-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0 dan ----------------------------------------------------------- O'Reilly && Associates argv@sun.com / argv@ora.com 632 Petaluma Ave, Sebastopol, CA 95472 800-338-NUTS, in CA: 800-533-NUTS, FAX 707-829-0104 Opinions expressed reflect those of the author only.